home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / include / libpurple / cipher.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-04  |  14.1 KB  |  449 lines
  1. /**
  2.  * @file cipher.h Purple Cipher API
  3.  * @ingroup core
  4.  *
  5.  * purple
  6.  *
  7.  * Purple is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  */
  25. #ifndef PURPLE_CIPHER_H
  26. #define PURPLE_CIPHER_H
  27.  
  28. #include <glib.h>
  29.  
  30. #define PURPLE_CIPHER(obj)            ((PurpleCipher *)(obj))            /**< PurpleCipher typecast helper            */
  31. #define PURPLE_CIPHER_OPS(obj)        ((PurpleCipherOps *)(obj))        /**< PurpleCipherInfo typecase helper        */
  32. #define PURPLE_CIPHER_CONTEXT(obj)    ((PurpleCipherContext *)(obj))    /**< PurpleCipherContext typecast helper    */
  33.  
  34. typedef struct _PurpleCipher            PurpleCipher;            /**< A handle to a PurpleCipher    */
  35. typedef struct _PurpleCipherOps        PurpleCipherOps;        /**< Ops for a PurpleCipher        */
  36. typedef struct _PurpleCipherContext    PurpleCipherContext;    /**< A context for a PurpleCipher    */
  37.  
  38.  
  39. /**
  40.  * The operation flags for a cipher
  41.  */
  42. typedef enum _PurpleCipherCaps {
  43.     PURPLE_CIPHER_CAPS_SET_OPT            = 1 << 1,        /**< Set option flag    */
  44.     PURPLE_CIPHER_CAPS_GET_OPT            = 1 << 2,        /**< Get option flag    */
  45.     PURPLE_CIPHER_CAPS_INIT                = 1 << 3,        /**< Init flag            */
  46.     PURPLE_CIPHER_CAPS_RESET                = 1 << 4,        /**< Reset flag            */
  47.     PURPLE_CIPHER_CAPS_UNINIT                = 1 << 5,        /**< Uninit flag        */
  48.     PURPLE_CIPHER_CAPS_SET_IV                = 1 << 6,        /**< Set IV flag        */
  49.     PURPLE_CIPHER_CAPS_APPEND                = 1 << 7,        /**< Append flag        */
  50.     PURPLE_CIPHER_CAPS_DIGEST                = 1 << 8,        /**< Digest flag        */
  51.     PURPLE_CIPHER_CAPS_ENCRYPT            = 1 << 9,        /**< Encrypt flag        */
  52.     PURPLE_CIPHER_CAPS_DECRYPT            = 1 << 10,        /**< Decrypt flag        */
  53.     PURPLE_CIPHER_CAPS_SET_SALT            = 1 << 11,        /**< Set salt flag        */
  54.     PURPLE_CIPHER_CAPS_GET_SALT_SIZE        = 1 << 12,        /**< Get salt size flag    */
  55.     PURPLE_CIPHER_CAPS_SET_KEY            = 1 << 13,        /**< Set key flag        */
  56.     PURPLE_CIPHER_CAPS_GET_KEY_SIZE        = 1 << 14,        /**< Get key size flag    */
  57.     PURPLE_CIPHER_CAPS_UNKNOWN            = 1 << 16        /**< Unknown            */
  58. } PurpleCipherCaps;
  59.  
  60. /**
  61.  * The operations of a cipher.  Every cipher must implement one of these.
  62.  */
  63. struct _PurpleCipherOps {
  64.     /** The set option function    */
  65.     void (*set_option)(PurpleCipherContext *context, const gchar *name, void *value);
  66.  
  67.     /** The get option function */
  68.     void *(*get_option)(PurpleCipherContext *context, const gchar *name);
  69.  
  70.     /** The init function */
  71.     void (*init)(PurpleCipherContext *context, void *extra);
  72.  
  73.     /** The reset function */
  74.     void (*reset)(PurpleCipherContext *context, void *extra);
  75.  
  76.     /** The uninit function */
  77.     void (*uninit)(PurpleCipherContext *context);
  78.  
  79.     /** The set initialization vector function */
  80.     void (*set_iv)(PurpleCipherContext *context, guchar *iv, size_t len);
  81.  
  82.     /** The append data function */
  83.     void (*append)(PurpleCipherContext *context, const guchar *data, size_t len);
  84.  
  85.     /** The digest function */
  86.     gboolean (*digest)(PurpleCipherContext *context, size_t in_len, guchar digest[], size_t *out_len);
  87.  
  88.     /** The encrypt function */
  89.     int (*encrypt)(PurpleCipherContext *context, const guchar data[], size_t len, guchar output[], size_t *outlen);
  90.  
  91.     /** The decrypt function */
  92.     int (*decrypt)(PurpleCipherContext *context, const guchar data[], size_t len, guchar output[], size_t *outlen);
  93.  
  94.     /** The set salt function */
  95.     void (*set_salt)(PurpleCipherContext *context, guchar *salt);
  96.  
  97.     /** The get salt size function */
  98.     size_t (*get_salt_size)(PurpleCipherContext *context);
  99.  
  100.     /** The set key function */
  101.     void (*set_key)(PurpleCipherContext *context, const guchar *key);
  102.  
  103.     /** The get key size function */
  104.     size_t (*get_key_size)(PurpleCipherContext *context);
  105.  
  106.     void (*_purple_reserved1)(void);
  107.     void (*_purple_reserved2)(void);
  108.     void (*_purple_reserved3)(void);
  109.     void (*_purple_reserved4)(void);
  110. };
  111.  
  112. #ifdef __cplusplus
  113. extern "C" {
  114. #endif /* __cplusplus */
  115.  
  116. /*****************************************************************************/
  117. /** @name PurpleCipher API                                                     */
  118. /*****************************************************************************/
  119. /*@{*/
  120.  
  121. /**
  122.  * Gets a cipher's name
  123.  *
  124.  * @param cipher The cipher handle
  125.  *
  126.  * @return The cipher's name
  127.  */
  128. const gchar *purple_cipher_get_name(PurpleCipher *cipher);
  129.  
  130. /**
  131.  * Gets a cipher's capabilities
  132.  *
  133.  * @param cipher The cipher handle
  134.  *
  135.  * @return The cipher's info
  136.  */
  137. guint purple_cipher_get_capabilities(PurpleCipher *cipher);
  138.  
  139. /**
  140.  * Gets a digest from a cipher
  141.  *
  142.  * @param name     The cipher's name
  143.  * @param data     The data to hash
  144.  * @param data_len The length of the data
  145.  * @param in_len   The length of the buffer
  146.  * @param digest   The returned digest
  147.  * @param out_len  The length written
  148.  *
  149.  * @return @c TRUE if successful, @c FALSE otherwise
  150.  */
  151. gboolean purple_cipher_digest_region(const gchar *name, const guchar *data, size_t data_len, size_t in_len, guchar digest[], size_t *out_len);
  152.  
  153. /*@}*/
  154. /******************************************************************************/
  155. /** @name PurpleCiphers API                                                      */
  156. /******************************************************************************/
  157. /*@{*/
  158.  
  159. /**
  160.  * Finds a cipher by it's name
  161.  *
  162.  * @param name The name of the cipher to find
  163.  *
  164.  * @return The cipher handle or @c NULL
  165.  */
  166. PurpleCipher *purple_ciphers_find_cipher(const gchar *name);
  167.  
  168. /**
  169.  * Registers a cipher as a usable cipher
  170.  *
  171.  * @param name The name of the new cipher
  172.  * @param ops  The cipher ops to register
  173.  *
  174.  * @return The handle to the new cipher or @c NULL if it failed
  175.  */
  176. PurpleCipher *purple_ciphers_register_cipher(const gchar *name, PurpleCipherOps *ops);
  177.  
  178. /**
  179.  * Unregisters a cipher
  180.  *
  181.  * @param cipher The cipher handle to unregister
  182.  *
  183.  * @return Whether or not the cipher was successfully unloaded
  184.  */
  185. gboolean purple_ciphers_unregister_cipher(PurpleCipher *cipher);
  186.  
  187. /**
  188.  * Gets the list of ciphers
  189.  *
  190.  * @return The list of available ciphers
  191.  * @note This list should not be modified, it is owned by the cipher core
  192.  */
  193. GList *purple_ciphers_get_ciphers(void);
  194.  
  195. /*@}*/
  196. /******************************************************************************/
  197. /** @name PurpleCipher Subsystem API                                              */
  198. /******************************************************************************/
  199. /*@{*/
  200.  
  201. /**
  202.  * Gets the handle to the cipher subsystem
  203.  *
  204.  * @return The handle to the cipher subsystem
  205.  */
  206. gpointer purple_ciphers_get_handle(void);
  207.  
  208. /**
  209.  * Initializes the cipher core
  210.  */
  211. void purple_ciphers_init(void);
  212.  
  213. /**
  214.  * Uninitializes the cipher core
  215.  */
  216. void purple_ciphers_uninit(void);
  217.  
  218. /*@}*/
  219. /******************************************************************************/
  220. /** @name PurpleCipherContext API                                                  */
  221. /******************************************************************************/
  222. /*@{*/
  223.  
  224. /**
  225.  * Sets the value an option on a cipher context
  226.  *
  227.  * @param context The cipher context
  228.  * @param name    The name of the option
  229.  * @param value   The value to set
  230.  */
  231. void purple_cipher_context_set_option(PurpleCipherContext *context, const gchar *name, gpointer value);
  232.  
  233. /**
  234.  * Gets the vale of an option on a cipher context
  235.  *
  236.  * @param context The cipher context
  237.  * @param name    The name of the option
  238.  * @return The value of the option
  239.  */
  240. gpointer purple_cipher_context_get_option(PurpleCipherContext *context, const gchar *name);
  241.  
  242. /**
  243.  * Creates a new cipher context and initializes it
  244.  *
  245.  * @param cipher The cipher to use
  246.  * @param extra  Extra data for the specific cipher
  247.  *
  248.  * @return The new cipher context
  249.  */
  250. PurpleCipherContext *purple_cipher_context_new(PurpleCipher *cipher, void *extra);
  251.  
  252. /**
  253.  * Creates a new cipher context by the cipher name and initializes it
  254.  *
  255.  * @param name  The cipher's name
  256.  * @param extra Extra data for the specific cipher
  257.  *
  258.  * @return The new cipher context
  259.  */
  260. PurpleCipherContext *purple_cipher_context_new_by_name(const gchar *name, void *extra);
  261.  
  262. /**
  263.  * Resets a cipher context to it's default value
  264.  * @note If you have set an IV you will have to set it after resetting
  265.  *
  266.  * @param context The context to reset
  267.  * @param extra   Extra data for the specific cipher
  268.  */
  269. void purple_cipher_context_reset(PurpleCipherContext *context, gpointer extra);
  270.  
  271. /**
  272.  * Destorys a cipher context and deinitializes it
  273.  *
  274.  * @param context The cipher context to destory
  275.  */
  276. void purple_cipher_context_destroy(PurpleCipherContext *context);
  277.  
  278. /**
  279.  * Sets the initialization vector for a context
  280.  * @note This should only be called right after a cipher context is created or reset
  281.  *
  282.  * @param context The context to set the IV to
  283.  * @param iv      The initialization vector to set
  284.  * @param len     The len of the IV
  285.  */
  286. void purple_cipher_context_set_iv(PurpleCipherContext *context, guchar *iv, size_t len);
  287.  
  288. /**
  289.  * Appends data to the context
  290.  *
  291.  * @param context The context to append data to
  292.  * @param data    The data to append
  293.  * @param len     The length of the data
  294.  */
  295. void purple_cipher_context_append(PurpleCipherContext *context, const guchar *data, size_t len);
  296.  
  297. /**
  298.  * Digests a context
  299.  *
  300.  * @param context The context to digest
  301.  * @param in_len  The length of the buffer
  302.  * @param digest  The return buffer for the digest
  303.  * @param out_len The length of the returned value
  304.  */
  305. gboolean purple_cipher_context_digest(PurpleCipherContext *context, size_t in_len, guchar digest[], size_t *out_len);
  306.  
  307. /**
  308.  * Converts a guchar digest into a hex string
  309.  *
  310.  * @param context  The context to get a digest from
  311.  * @param in_len   The length of the buffer
  312.  * @param digest_s The return buffer for the string digest
  313.  * @param out_len  The length of the returned value
  314.  */
  315. gboolean purple_cipher_context_digest_to_str(PurpleCipherContext *context, size_t in_len, gchar digest_s[], size_t *out_len);
  316.  
  317. /**
  318.  * Encrypts data using the context
  319.  *
  320.  * @param context The context
  321.  * @param data    The data to encrypt
  322.  * @param len     The length of the data
  323.  * @param output  The output buffer
  324.  * @param outlen  The len of data that was outputed
  325.  *
  326.  * @return A cipher specific status code
  327.  */
  328. gint purple_cipher_context_encrypt(PurpleCipherContext *context, const guchar data[], size_t len, guchar output[], size_t *outlen);
  329.  
  330. /**
  331.  * Decrypts data using the context
  332.  *
  333.  * @param context The context
  334.  * @param data    The data to encrypt
  335.  * @param len     The length of the returned value
  336.  * @param output  The output buffer
  337.  * @param outlen  The len of data that was outputed
  338.  *
  339.  * @return A cipher specific status code
  340.  */
  341. gint purple_cipher_context_decrypt(PurpleCipherContext *context, const guchar data[], size_t len, guchar output[], size_t *outlen);
  342.  
  343. /**
  344.  * Sets the salt on a context
  345.  *
  346.  * @param context The context who's salt to set
  347.  * @param salt    The salt
  348.  */
  349. void purple_cipher_context_set_salt(PurpleCipherContext *context, guchar *salt);
  350.  
  351. /**
  352.  * Gets the size of the salt if the cipher supports it
  353.  *
  354.  * @param context The context who's salt size to get
  355.  *
  356.  * @return The size of the salt
  357.  */
  358. size_t purple_cipher_context_get_salt_size(PurpleCipherContext *context);
  359.  
  360. /**
  361.  * Sets the key on a context
  362.  *
  363.  * @param context The context who's key to set
  364.  * @param key     The key
  365.  */
  366. void purple_cipher_context_set_key(PurpleCipherContext *context, const guchar *key);
  367.  
  368. /**
  369.  * Gets the key size for a context
  370.  *
  371.  * @param context The context who's key size to get
  372.  *
  373.  * @return The size of the key
  374.  */
  375. size_t purple_cipher_context_get_key_size(PurpleCipherContext *context);
  376.  
  377. /**
  378.  * Sets the cipher data for a context
  379.  *
  380.  * @param context The context who's cipher data to set
  381.  * @param data    The cipher data to set
  382.  */
  383. void purple_cipher_context_set_data(PurpleCipherContext *context, gpointer data);
  384.  
  385. /**
  386.  * Gets the cipher data for a context
  387.  *
  388.  * @param context The context who's cipher data to get
  389.  *
  390.  * @return The cipher data
  391.  */
  392. gpointer purple_cipher_context_get_data(PurpleCipherContext *context);
  393.  
  394. /*@}*/
  395. /*****************************************************************************/
  396. /** @name Purple Cipher HTTP Digest Helper Functions                             */
  397. /*****************************************************************************/
  398. /*@{*/
  399.  
  400. /**
  401.  * Calculates a session key for HTTP Digest authentation
  402.  *
  403.  * See RFC 2617 for more information.
  404.  *
  405.  * @param algorithm    The hash algorithm to use
  406.  * @param username     The username provided by the user
  407.  * @param realm        The authentication realm provided by the server
  408.  * @param password     The password provided by the user
  409.  * @param nonce        The nonce provided by the server
  410.  * @param client_nonce The nonce provided by the client
  411.  *
  412.  * @return The session key, or @c NULL if an error occurred.
  413.  */
  414. gchar *purple_cipher_http_digest_calculate_session_key(
  415.         const gchar *algorithm, const gchar *username,
  416.         const gchar *realm, const gchar *password,
  417.         const gchar *nonce, const gchar *client_nonce);
  418.  
  419. /** Calculate a response for HTTP Digest authentication
  420.  *
  421.  * See RFC 2617 for more information.
  422.  *
  423.  * @param algorithm         The hash algorithm to use
  424.  * @param method            The HTTP method in use
  425.  * @param digest_uri        The URI from the initial request
  426.  * @param qop               The "quality of protection"
  427.  * @param entity            The entity body
  428.  * @param nonce             The nonce provided by the server
  429.  * @param nonce_count       The nonce count
  430.  * @param client_nonce      The nonce provided by the client
  431.  * @param session_key       The session key from purple_cipher_http_digest_calculate_session_key()
  432.  *
  433.  * @return The hashed response, or @c NULL if an error occurred.
  434.  */
  435. gchar *purple_cipher_http_digest_calculate_response(
  436.         const gchar *algorithm, const gchar *method,
  437.         const gchar *digest_uri, const gchar *qop,
  438.         const gchar *entity, const gchar *nonce,
  439.         const gchar *nonce_count, const gchar *client_nonce,
  440.         const gchar *session_key);
  441.  
  442. /*@}*/
  443.  
  444. #ifdef __cplusplus
  445. }
  446. #endif /* __cplusplus */
  447.  
  448. #endif /* PURPLE_CIPHER_H */
  449.